/*
 *  Copyright 2004 Blandware (http://www.blandware.com)
 *
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 */
package com.blandware.atleap.persistence.core;

import com.blandware.atleap.common.util.PartialCollection;
import com.blandware.atleap.common.util.QueryInfo;
import com.blandware.atleap.persistence.exception.BackupFileAccessException;

import java.util.Date;
import java.io.InputStream;

/**
 * <p>DAO for performing backup/restore database operations</p>
 * <p/>
 * <p><a href="BackupDAO.java.html"><i>View Source</i></a></p>
 *
 * @author Andrey Grebnev <a href="mailto:andrey.grebnev@blandware.com">&lt;andrey.grebnev@blandware.com&gt;</a>
 * @version $Revision: 1.5 $ $Date: 2007/06/06 13:43:00 $
 */
public interface BackupDAO extends DAO  {

    /**
     * Backup database into file
     *
     * @throws com.blandware.atleap.persistence.exception.BackupFileAccessException
     * thrown if directory/file access is prohibeted
     */
    public void backup() throws BackupFileAccessException;

    /**
     * <p>
     * Restores database from archive specified by date. If date is null we will try to restore from initial xml resource
     * e.g. initial-data.xml
     * </p>
     * <p>
     * If <b>force</b> is <code>false</code>, then, if tables already exist,
     * nothing will be made at all: all data will remain untouched in database.
     * </p>
     *
     * @param date date of archive
     * @param force if it is <code>false</code> we will create tables and load data only if tables do not exist. If it is <code>true</code>
     * we will drop and create tables and load data.
     * @throws com.blandware.atleap.persistence.exception.BackupFileAccessException
     * thrown if directory/file access is prohibeted
     */
    public void restore(Date date, Boolean force) throws BackupFileAccessException;

    /**
     * Restores database from data supplied by input stream.
     *
     * @param inputStream stream to supply data
     * @param force if it is <code>false</code> we will create tables and load data only if tables do not exist. If it is <code>true</code>
     * we will drop and create tables and load data.
     */
    public void restore(InputStream inputStream, Boolean force);

    /**
     * Returns whether list of archives is accessible or not (due to directory
     * permissions, for example)
     *
     * @return whether list of archives is accessible
     */
    public boolean canListArchives();

    /**
     * Retrieves filtered/sorted collection of archives.
     *
     * @param queryInfo Object that contains information about how to filter and sort data
     * @return Collection of archives' dates
     * @throws com.blandware.atleap.persistence.exception.BackupFileAccessException
     * thrown if directory/file access is prohibeted
     */
    public PartialCollection listArchives(QueryInfo queryInfo) throws BackupFileAccessException;

    /**
     * Tries to create a dbbackup directory if it does not exist
     *
     * @return true if dbbackup directory already exists or was created
     * successfully.
     */
    public boolean createDirIfNotExists();

    /**
     * Returns data of zipped backup for a given date; if no such backup exists,
     * returns <code>null</code>.
     *
     * @param date date of backup
     * @return array of bytes or <code>null</code> if no such backup
     */
    public byte[] getBackupFileData(Date date);

    /**
     * Returns name of file that corresponds to a given date. This file is not
     * guaranteed to exist.
     *
     * @param date date of backup
     * @return file name
     */
    public String getBackupFileName(Date date);
}
